Inside Macintosh: Operating System Utilities /: Chapter 4 - Date, Time, and Measurement Utilities

Summary of the Date, Time, and Measurement Utilities

Pascal Summary

Constants

CONST
   {date equates for ToggleDate control bits}
   validDateFields      = -1;       {date fields are valid}
   genCdevRangeBit      = 27;       {restrict date/time to range used by }
                                    { General Controls control panel}
   togDelta12HourBit    = 28;       {if toggling hour up/down, restrict to }
                                    { 12-hour range}
   togCharZCycleBit     = 29;       {modifier for togChar12HourBit to }
                                    { accept hours 0..11 only}
   togChar12HourBit     = 30;       {if toggling hour by char, accept }
                                    { hours 1..12 only}
   smallDateBit         = 31;       {restrict valid date/time to range }
                                    { of Time global}

   {long date-time record field masks}
   eraMask              = $0001;    {era}
   yearMask             = $0002;    {year}
   monthMask            = $0004;    {month}
   dayMask              = $0008;    {day}
   hourMask             = $0010;    {hour}
   minuteMask           = $0020;    {minute}
   secondMask           = $0040;    {second}
   dayOfWeekMask        = $0080;    {day of the week}
   dayOfYearMask        = $0100;    {day of the year}
   weekOfYearMask       = $0200;    {week of the year}
   pmMask               = $0400;    {evening (P.M.)}

   {default value for togFlags field in the toggle parameter block }
   { and default value for the flags parameter passed to the Verify function}
   dateStdMask          = $007F;    {default value for checking era }
                                    { through second fields}

Data Types

TYPE 
   DateTimeRec =              {date-time record}
   RECORD
      year:       Integer;    {year}
      month:      Integer;    {month}
      day:        Integer;    {day of the month}
      hour:       Integer;    {hour}
      minute:     Integer;    {minute}
      second:     Integer;    {second}
      dayOfWeek:  Integer;    {day of the week}
   END;

   LongDateField =   {long date field enumeration}
                     (eraField, yearField, monthField, dayField,
                     hourField, minuteField, secondField,dayOfWeekField,
                     dayOfYearField,weekOfYearField, pmField, res1Field,
                     res2Field, res3Field);
   LongDateTime = comp;       {date and time in 64-bit SANE comp format}

   LongDateCvt =              {long date-time conversion record}
   RECORD
      CASE Integer OF
         0:
            (c:      comp);   {copy field into a variable of type }
                              { LongDateTime}
         1:
            (lHigh:  LongInt; {high-order 32 bits}
             lLow:   LongInt);{low-order 32 bits}
   END;

   LongDateRec =              {long date-time record}
   RECORD
      CASE Integer OF
         0:
            (era:          Integer;       {era}
             year:         Integer;       {year}
             month:        Integer;       {month}
             day:          Integer;       {day of the month}
             hour:         Integer;       {hour}
             minute:       Integer;       {minute}
             second:       Integer;       {second}
             dayOfWeek:    Integer;       {day of the week}
             dayOfYear:    Integer;       {day of the year}
             weekOfYear:   Integer;       {week of the year}
             pm:           Integer;       {half of day--0 for morning, }
                                          { 1 for evening}
             res1:         Integer;       {reserved}
             res2:         Integer;       {reserved}
             res3:         Integer);      {reserved}
         1:                               {index by LongDateField}
            (list:         ARRAY[0..13] OF Integer);
         2:
            (eraAlt:       Integer;       {era}
             oldDate:      DateTimeRec);  {date-time record}
   END;

   TogglePB =                    {toggle parameter block}
   RECORD
      togFlags:      LongInt;    {flags}
      amChars:       ResType;    {from 'itl0' resource, but made uppercase}
      pmChars:       ResType;    {from 'itl0' resource, but made uppercase}
                                 {reserved}
      reserved:      ARRAY[0..3] OF LongInt;

   END;

   ToggleResults = Integer;         {ToggleDate function return type}

   DateDelta = SignedByte;          {ToggleDate function delta field type}

   MachineLocation =                   {geographic location record}
   RECORD
      latitude:            Fract;      {latitude}
      longitude:           Fract;      {longitude}
      CASE Integer OF
         0:
            (dlsDelta:     SignedByte);{daylight savings time}
         1:
            (gmtDelta:     LongInt);   {Greenwich mean time}
   END;
   UnsignedWide =          {Microseconds procedure return type}
   PACKED RECORD
   hi:   longInt;       {high-order 32 bits}
   lo:   longInt;       {low-order 32 bits}
   END;

Routines

Getting the Current Date and Time

FUNCTION ReadDateTime		(VAR time: LongInt) : OSErr;
PROCEDURE GetDateTime 		(VAR secs: LongInt);
PROCEDURE GetTime 		(VAR d: DateTimeRec);

Setting the Current Date and Time

FUNCTION SetDateTime		(time: LongInt) : OSErr;
PROCEDURE SetTime		(d: DateTimeRec);

Converting Between Date-Time Formats

{each procedure has two spellings, see Table 4-4 for the alternate spelling}
PROCEDURE SecondsToDate 	(secs: LongInt; VAR d: DateTimeRec);
PROCEDURE DateToSeconds 	(d: DateTimeRec; VAR secs: LongInt);

Converting Between Long Date-Time Formats

{each procedure has two spellings, see Table 4-4 for the alternate spelling}
PROCEDURE LongSecondsToDate	(VAR lSecs: LongDateTime;
				VAR lDate: LongDateRec);
PROCEDURE LongDateToSeconds	(lDate: LongDateRec; VAR lSecs: LongDateTime);

Modifying and Verifying Long Date-Time Records

FUNCTION ToggleDate		(VAR lSecs: LongDateTime; field: LongDateField;
				delta: DateDelta; ch: Integer;
				params: TogglePB): ToggleResults;
FUNCTION ValidDate		(vDate: LongDateRec; flags: LongInt;
				VAR newSecs: LongDateTime): Integer;

Reading and Writing Location Data

PROCEDURE ReadLocation		(VAR loc: MachineLocation);
PROCEDURE WriteLocation		(VAR loc: MachineLocation);

Determining the Measurement System

{this function has two spellings, see Table 4-4 for the alternate spelling}
FUNCTION IsMetric:Boolean;

Measuring Time

PROCEDURE Microseconds		(VAR microTickCount UnsignedWide);

C Summary

Constants

enum
{
   /*date equates for ToggleDate control bits*/
   validDateFields      = -1,       /*date fields are valid*/
   genCdevRangeBit      = 27,       /*restrict date/time to range used by */
                                    /* General Controls control panel*/
   togDelta12HourBit    = 28,       /*if toggling hour up/down, restrict */
                                    /* to 12-hour range*/
   togCharZCycleBit     = 29,       /*modifier for TogChar12HourBit to */
                                    /* accept hours 0..11 only*/
   togChar12HourBit     = 30,       /*if toggling hour by char, accept */
                                    /* hours 1..12 only*/
   smallDateBit         = 31,       /*restrict valid date/time to range */
                                    /* of Time global*/

   /*long date-time record field masks*/
   eraMask              = 0x0001,   /*era*/
   yearMask             = 0x0002,   /*year*/
   monthMask            = 0x0004,   /*day*/
   dayMask              = 0x0008,   /*month*/
   hourMask             = 0x0010,   /*hour*/
   minuteMask           = 0x0020,   /*minute*/
   secondMask           = 0x0040,   /*second*/
   dayOfWeekMask        = 0x0080,   /*day of the week*/
   dayOfYearMask        = 0x0100,   /*day of the year*/
   weekOfYearMask       = 0x0200,   /*week of the year*/
   pmMask               = 0x0400    /*evening (P.M.)*/
};

enum
{
   /*default value for togFlags field in the toggle parameter block and */
   /* default value for the flags parameter passed to the Verify function*/
   dateStdMask          = 0x007F,   /*default value for checking era */
                                    /* through second fields*/
};

Data Types

struct DateTimeRec         /*date-time record*/
{
   short       year;       /*year*/
   short       month;      /*month*/
   short       day;        /*day of the month*/
   short       hour;       /*hour*/
   short       minute;     /*minute*/
   short       second;     /*second*/
   short       dayOfWeek;  /*day of the week*/
};
typedef struct DateTimeRec DateTimeRec;

enum                       /*long date field enumeration*/
{
   eraField, yearField, monthField, dayField, hourField, minuteField,
   secondField,dayOfWeekField, dayOfYearField, weekOfYearField, pmField,
   res1Field, res2Field, res3Field
};
typedef unsigned char LongDateField;

typedef comp LongDateTime;    /*date and time in 64-bit SANE comp format*/

union LongDateCvt             /*long date-time conversion record*/
{
   comp     c;                /*copy field into a LongDateTime variable*/
   struct
   {
      long  lHigh;            /*high-order 32 bits*/
      long  lLow;             /*low-order 32 bits*/
   } hl;
};
typedef union LongDateCvt LongDateCvt;

union LongDateRec             /*long date-time record*/
{
   struct
   {
      short era;              /*era*/
      short year;             /*year*/
      short month;            /*month*/
      short day;              /*day of the month*/
      short hour;             /*hour*/
      short minute;           /*minute*/
      short second;           /*second*/
      short dayOfWeek;        /*day of the week*/
      short dayOfYear;        /*day of the year*/
      short weekOfYear;       /*week of the year*/
      short pm;               /*half of day--0 for morning, 1 for evening*/
      short res1;             /*reserved*/
      short res2;             /*reserved*/
      short res3;             /*reserved*/
   } ld;
   short list[14];            /*index by LongDateField*/
   struct
   {
      short       eraAlt;     /*era*/
      DateTimeRec oldDate;    /*date-time record*/
   } od;
};
typedef union LongDateRec LongDateRec;

struct TogglePB               /*toggle parameter block*/
{
   long     togFlags;         /*flags*/
   ResType  amChars;          /*from 'itl0' resource, but made uppercase*/
   ResType  pmChars;          /*from 'itl0' resource, but made uppercase*/
   long     reserved[4];      /*reserved*/
};
typedef struct TogglePB TogglePB;
typedef short ToggleResults;  /*ToggleDate function return type*/
typedef char DateDelta;       /*ToggleDate function delta field type*/
struct MachineLocation        /*geographic location record*/
{
   Fract    latitude;         /*latitude*/
   Fract    longitude;        /*longitude*/
   union
   {
      char  dlsDelta;         /*daylight saving time*/
      long  gmtDelta;         /*Greenwich mean time*/
   } gmtFlags;
};
typedef struct MachineLocation MachineLocation;
struct UnsignedWide           /*Microseconds procedure return type*/
{
   unsigned long     hi;      /*high-order 32 bits*/
   unsigned long     lo;      /*high-order 32 bits*/
};
typedef struct UnsignedWide UnsignedWide;

Routines

Getting the Current Date and Time

pascal OSErr ReadDateTime	(unsigned long *time);
pascal void GetDateTime 	(unsigned long *secs);
pascal void GetTime 		(DateTimeRec *d);

Setting the Current Date and Time

pascal OSErr SetDateTime	(unsigned long time);
pascal void SetTime		(const DateTimeRec *d);

Converting Between Date-Time Formats

{each procedure has two spellings, see Table 4-4 for the alternate spelling}
pascal void SecondsToDate	(unsigned long secs, DateTimeRec *d);
pascal void DateToSeconds 	(const DateTimeRec *d, unsigned long *secs);

Converting Between Long Date-Time Formats

{each procedure has two spellings, see Table 4-4 for the alternate spelling}
pascal void LongSecondsToDate
   				(LongDateTime *lSecs, LongDateRec *lDate);
pascal void LongDateToSeconds
				(const LongDateRec *lDate, LongDateTime *lSecs);

Modifying and Verifying Long Date-Time Records

pascal ToggleResults ToggleDate
				(LongDateTime *lSecs, LongDateField field,
				DateDelta delta, short ch,
				const TogglePB *params);
pascal short ValidDate		(const LongDateRec vDate, long flags,
 				LongDateTime *newSecs);

Reading and Writing Location Data

pascal void ReadLocation	(MachineLocation *loc);
pascal void WriteLocation	(MachineLocation *loc);

Determining the Measurement System

{this functiosn has two spellings, see Table 4-4 for the alternate spelling}
pascal Boolean IsMetric		(void);

Measuring Time

pascal void Microseconds	(UnsignedWide *microTickCount);

Assembly-Language Summary

Data Structures

Date-Time Record
0 dtYear word year
2 dtMonth word month
4 dtDay word day of the month
6 dtHour word hour
8 dtMinute word minute
10 dtSecond word second
12 dtDayOfWeek word day of the week

Long Date Field Enumeration
0 eraField byte era
1 yearField byte year
2 monthField byte month
3 dayField byte day of the month
4 hourField byte hour
5 minuteField byte minute
6 secondField byte second
7 dayOfWeekField byte day of the week
8 dayOfYearField byte day of the year
9 weekOfYearField byte week of the year
10 pmField byte pm
11 res1Field byte reserved
12 res2Field byte reserved
13 res3Field byte reserved

Long Date-Time Value
0 highLong long high-order 32 bits
4 lowLong long low-order 32 bits

Long Date-Time Record
0 era word era
2 year word year
4 month word month
6 day word day of the month
8 hour word hour
10 minute word minute
12 second word second
14 dayOfWeek word day of the week
16 dayOfYear word day of the year
18 weekOfYear word week of the year
20 pm word half of day, morning or evening
22 ldReserved 6 bytes reserved

0 latitude long latitude
4 longitude long longitude
8 dlsDelta byte daylight savings time
9 gmtDelta 3 bytes Greenwich mean time
Geographic Location Record

Toggle Parameter Block
0 togFlags long flags
2 amChars word ResType from `'itl0'` made uppercase
4 pmChars word ResType from `'itl0'` made uppercase
6 reserved word reserved

Unsigned Wide Record
0 hi long high-order 32 bits
4 lo long low-order 32 bits

Global Variables
Time The number of seconds since midnight, January 1, 1904

Result Codes
toggleErr5 9 Reserved
toggleErr4 8 Reserved
toggleErr3 7 Reserved
toggleOutOfRange 7 Out of range (synonym for `toggleErr3`)
toggleBadNum 6 Tried to use character as number
toggleUnknown 5 Unknown error
toggleBadChar 4 Invalid character
toggleBadDelta 3 Invalid delta value
toggleBadField 2 Invalid field number
toggleOK 1 No error
toggleUndefined 0 Undefined error
noErr 0 No error
clkRdErr -85 Unable to read clock
clkWrErr -86 Time written did not verify

0	dtYear	word	year
2	dtMonth	word	month
4	dtDay	word	day of the month
6	dtHour	word	hour
8	dtMinute	word	minute
10	dtSecond	word	second
12	dtDayOfWeek	word	day of the week

0	eraField	byte	era
1	yearField	byte	year
2	monthField	byte	month
3	dayField	byte	day of the month
4	hourField	byte	hour
5	minuteField	byte	minute
6	secondField	byte	second
7	dayOfWeekField	byte	day of the week
8	dayOfYearField	byte	day of the year
9	weekOfYearField	byte	week of the year
10	pmField	byte	pm
11	res1Field	byte	reserved
12	res2Field	byte	reserved
13	res3Field	byte	reserved

0	highLong	long	high-order 32 bits
4	lowLong	long	low-order 32 bits

0	latitude	long	latitude
4	longitude	long	longitude
8	dlsDelta	byte	daylight savings time
9	gmtDelta	3 bytes	Greenwich mean time

0	togFlags	long	flags
2	amChars	word	ResType from `'itl0'` made uppercase
4	pmChars	word	ResType from `'itl0'` made uppercase
6	reserved	word	reserved

toggleErr5	9	Reserved
toggleErr4	8	Reserved
toggleErr3	7	Reserved
toggleOutOfRange	7	Out of range (synonym for `toggleErr3`)
toggleBadNum	6	Tried to use character as number
toggleUnknown	5	Unknown error
toggleBadChar	4	Invalid character
toggleBadDelta	3	Invalid delta value
toggleBadField	2	Invalid field number
toggleOK	1	No error
toggleUndefined	0	Undefined error
noErr	0	No error
clkRdErr	-85	Unable to read clock
clkWrErr	-86	Time written did not verify

Summary of the Date, Time, and Measurement Utilities

Pascal Summary

Constants

Data Types

Routines

Getting the Current Date and Time

Setting the Current Date and Time

Converting Between Date-Time Formats

Converting Between Long Date-Time Formats

Modifying and Verifying Long Date-Time Records

Reading and Writing Location Data

Determining the Measurement System

Measuring Time

C Summary

Constants

Data Types

Routines

Getting the Current Date and Time

Setting the Current Date and Time

Converting Between Date-Time Formats

Converting Between Long Date-Time Formats

Modifying and Verifying Long Date-Time Records

Reading and Writing Location Data

Determining the Measurement System

Measuring Time

Assembly-Language Summary

Data Structures

Date-Time Record 0dtYearwordyear 2dtMonthwordmonth 4dtDaywordday of the month 6dtHourwordhour 8dtMinutewordminute 10dtSecondwordsecond 12dtDayOfWeekwordday of the week

Long Date-Time Value 0highLonglonghigh-order 32 bits 4lowLonglonglow-order 32 bits

0latitudelonglatitude 4longitudelonglongitude 8dlsDeltabytedaylight savings time 9gmtDelta3 bytesGreenwich mean time Geographic Location Record

Toggle Parameter Block 0togFlagslongflags 2amCharswordResType from 'itl0' made uppercase 4pmCharswordResType from 'itl0' made uppercase 6reservedwordreserved

Unsigned Wide Record 0hilonghigh-order 32 bits 4lolonglow-order 32 bits

Global Variables TimeThe number of seconds since midnight, January 1, 1904

Date-Time Record
0 dtYear word year
2 dtMonth word month
4 dtDay word day of the month
6 dtHour word hour
8 dtMinute word minute
10 dtSecond word second
12 dtDayOfWeek word day of the week

Long Date-Time Value
0 highLong long high-order 32 bits
4 lowLong long low-order 32 bits

0 latitude long latitude
4 longitude long longitude
8 dlsDelta byte daylight savings time
9 gmtDelta 3 bytes Greenwich mean time
Geographic Location Record

Toggle Parameter Block
0 togFlags long flags
2 amChars word ResType from `'itl0'` made uppercase
4 pmChars word ResType from `'itl0'` made uppercase
6 reserved word reserved

Unsigned Wide Record
0 hi long high-order 32 bits
4 lo long low-order 32 bits

Global Variables
Time The number of seconds since midnight, January 1, 1904